mandb−2.3.x−thedatabasecachedmanualpagersuite GraemeW.Wilford<eep2gw@ee.surrey.ac.uk> Thisdocumentdescribesthesetup,maintenanceanduseofagenericonline manualpagesystemwithspecialreferencetomandb−2.3.xandit’sadvanced features. mandb−2.3.x manualv0.5 April18,1995 UNIXisaregisteredtrademarkoftheX/OpenCompany,Ltd. NFSisaregisteredtrademarkofSunMicrosystems,Inc. PostScriptisaregisteredtrademarkofAdobeintheUnitedStates. Thegeneralconventionsusedthroughoutthismanualinclude •filenamesandpathsinitalic,eg./usr/man. •variablestrings(usuallypathcomponents)enclosedwithin<>andinitalic,eg.<sec>, •programnamesinbold,eg.man. •commandsthatcanbetypedatashellpromptinabox,eg.manfoobar. •environmentvariablesdenotedasfollows:$ENVVAR Copyright◯c1995GraemeW.Wilford Permissionisgrantedtomakeanddistributeverbatimcopiesofthismanualprovidedthecopyrightnoticeandthispermissionnoticearepreservedonallcopies. Permissionisgrantedtocopyanddistributemodifiedversionsofthismanualundertheconditions forverbatimcopying,providedthattheentireresultingderivedworkisdistributedunderthe termsofanoticeidenticaltothisone. Permissionisgrantedtocopyanddistributetranslationsofthismanualintoanotherlanguage, undertheaboveconditionsformodifiedversions,exceptthatthispermissionnoticemaybestated inatranslationapprovedbythecopyrightholder. mandb−2.3.x manualv0.5 April18,1995 1.Introduction 1.1.mandb−2.3.x mandb−2.3.xisapackagethatisdesignedtoprovideuserswithonlineinformationinafastand friendlymannerwhileatthesametimeofferingflexibilitytothesystemadministrator. Itismadeupofseveraluserprograms: •man−aninterfacetotheon-linereferencemanuals •whatis−searchthemanualpagenames •apropos−searchthemanualpagenamesanddescriptions •manpath−determinesearchpathformanualpages severalmaintenanceprograms: •mandb−createorupdatethemanualpageindexcaches •catman−createorupdatethepre-formattedmanualpages andaspecialpre-formatterthatknowsaboutcompressedmanualpages •zsoelim−satisfy.sorequestsinroffinput Inadditiontothesecompiledprograms,therearetwoshellscripts,mkcatdirsandcheckmanin thetoolssubdirectory.Thesescriptsaidthecreationofcatdirectoriesandcheckforduplicated manualpages,respectively. Thefollowingmanualpagesareprovidedwiththispackagetoexplaincorrectformatandusage. man(1),whatis(1),apropos(1),manpath(1),manpath(5),mandb(8),catman(8)andzsoelim(1). 1.1.1.Theconcept mandb−2.3.xoriginallystartedoutlifeasprogramsuiteman−1.1B,writtenbyJohnW.Eaton <jwe@che.utexas.edu>andmaintainedbyRikFaith<faith@cs.unc.edu>towhichsupportproposedbythenewlyformedFSSTNDcommitteeregardingcatdirectorieswasadded. Sincethen,mandb−2.3.x’smostinnovativefeature:thedatabasecachescheme1hasbeensignificantlydeveloped.Thebasicideawastoreducemanualpagesearchtimestoaminimum.Thefollowingpieceoftextisincludedfromthemandb-2.2distribution: Thetheory:Ifyougotoalibrarytotakeabookout,whatdoyoudo? a)Goandlookwhereitmightbeonamicro-fiche/terminal,takealook whereitissupposedtobeontheshelf,andthengolookatthenew arrivalsifit’snotwhereit’ssupposedtobe? OR b)Startatoneendofthegroundfloor,lookalongeverybookshelf untilyou’vecompletedthatfloor,thengoupalevelandstartagain untilyou’vefoundwhatyou’relookingfor? Sincethenthedatabaseindexschemehasevolvedgreatly.Everymanualpageandstraycatpage onthesystemisregisteredinanindexdatabasecachewhichstoresvariousdetailsaboutthefile 1originallyconceivedafterobservingtheactionsoftheperlbasedmanualpagersuite,man-plwrittenbyTomChris-tiansen<tchrist@convex.com> 1 mandb−2.3.x manualv0.5 April18,1995 includingthetimestamp,thelocationandthewhatis2information.Thisinformationiskeptupto datebymanwhichlooksforfilesystemchangeseachtimeitisinvoked. 1.2.Themanualpagesystem Thesimplestmanualpagesystemwillhaveasinglemanualpagehierarchy.Thiswilltypicallybe /usr/man beneathwhichwillbeseveralsubdirectoriesoftheformman<sec>where<sec>is1,2,3,4,5, 6,7or8.Thesearereferredtoassectionsofthemanual.Othersmayexistandtheyarenot restrictedtosinglecharacternames.eg. /usr/man/manfoo isavalidsectionsubdirectory.Othercommonsectionsinclude9,n,l,pando. Withinthesesectionsubdirectoriesresidethemanualpagesthemselves.Theirfilenamesfollowthe pattern /usr/man/man<sec>/<name>.<sec><ext> whereinmostcases<ext>isanemptystring.Anexampleismanualpagecp /usr/man/man1/cp.1 whichresidesinsection1andhasnospecialextension. 1.3.Sectionsofthemanual Themanualissplitupintosectionstoeaseaccessandtocaterformanualpagesthatsharethe samename.Itiscommonforaprogramandfunctiontosharethesamename.killisagood example.Thisisbothaprogramwhichcanbeusedtosendaprocessasignalandanoperating systemcallwithsimilarfunctionality.Theirmanualpagesarestoredundersections1and2 respectively.Thus,sectionsareusedtoseparateouttheprogrammanualpagesfromthefunction manualpagesandsoon.Thetablebelowshowsthesectionnumbersofthemanualfollowedby thetypesofpagestheycontain. SectionSectioncontents 1userexecutableprogramsorshellcommands 2systemcalls(functionsprovidedbythekernel) 3librarycalls(functionswithinsystemlibraries) 4specialfiles(usuallyfoundin/dev) 5fileformatsandconventionseg./etc/passwd 6games 7macropackagesandconventionseg.man(7),groff(7). 8systemadministrationcommands 9kernelroutines[Nonstandard] nnew[obsolete] llocal[obsolete] ppublic[obsolete] oold[obsolete] 2onelinedescriptionofthemanualpage 2 mandb−2.3.x manualv0.5 April18,1995 1.4.Theformatofmanualpages TheformatinwhichmanualpagesarestoredisNROFF/TROFFormoregenerallyROFF.This isatypesetterstylelanguage3whichrequiresformattingbeforebeingviewed.Infactsomemanual pagesrequirepre-formatprocessingtocorrectlyformattablesorequations. Ifthepageistobeviewedonscreeninatextenvironment,NROFFisusedastheprimaryformatter.Ifthepageistobeprintedordisplayedinagraphicalenvironment,TROFFisused.Traditionally,TROFFformattedfilesforaC/A/T(ComputeraidedTypesetter)whichisnowobsolete. TheGNUROFF(GROFF4)suiteofprogramsofferachoiceofoutputtypesincludingX,dviand postscript.Whenconfiguringmandb−2.3.x,thepreferenceistouseGROFFratherthan TROFF. 1.5.Argumentstoconfigure Toallowtheconfigurationprogram,configure,tobenon-interactive,itcanbepassedvarious optionstoalterthedefaultsettings.Genericconfigureoptionsarediscussedindocs/INSTALL. Optionsthatarespecifictothemandb−2.3.xpackagearedescribedbelow. −−enable−debug Bydefault,theconfigurationprocesscreatesproductionqualityMakefiles.Thisoption, whichtakesnoargument,changescertainvaluestoaidindebuggingmandb−2.3.x.Itdoes notalterthephysicalbehaviourofanyoftheprograms. −−enable−setuid[=ARG] Bydefault,manwillbeinstalledasasetuidprogramtouserman.Usethisoptionwithan argumenttochangethesetuidowner. −−disable−setuid Usethisoptiontoinstallmanasanon-setuidprogramandtochangethedefaultcatand databasefiles’accessflagstoallowuserstomodifythem. −−with−device=DEVICE UsethisflagtoalterthedefaultoutputdeviceusedbyNROFF.DEVICEispassedto NROFFwiththe−Toption.configurewilltestthatNROFFwillrunwiththesupplied deviceargument. −−with−db=LIBRARY configurewilllookfordatabaseinterfacelibrariesintheorderBerkeleyDB,gdbmand finallyndbmandwill#defineappropriatevariablesrelativetothefirstonefound.Tooverridethebuiltinorderonplatformshavingachoiceofinterfacelibrary,usethisoptionto specifywhichlibrarytouse. 3similarinsomeaspectstoTeX 4WrittenandmaintainedbyJamesClark<jjc@jclark.com> 3 mandb−2.3.x manualv0.5 April18,1995 2.ThespecificsofSections 2.1.Packagespecificmanualpagesections Theuseofpackagespecificmanualpagesectionsisdiscouragedaspackageslargeenoughtowarranttheirownsectionprobablycontainmanualpagesthatspanothersections.Anexamplemight bepackagefoothathasit’sownsection /usr/man/manfoo whichcontainsmanualpagesdescribingit’sprograms,thelibraryroutinesitoffersandtheformat ofseveralofitsconfigurationfiles.Thesepageswouldnormallybeallocatedtosections1,3and5 respectivelyandthuscombiningthemallundersectionfooismisleading.Subtleproblemswill ariseifthereareanybasename-spaceclasheswithstandardmanualpages,eg.exit(3),exit(foo) andtheorderinwhichtheyshouldbeshown. Therearetwostandardsolutionstothisproblem. (1)Createaseparatemanualpagehierarchyforthepackage’smanualpagessuchas /usr/local/packages/foo/man (2)Installthepagesintheirrelevantsections,withauniqueextensionappendedtothefilenamesuchthat /usr/man/manfoo/exit.foo wouldinsteadbeinstalledas /usr/man/man1/exit.1foo Only(2)offersacompletesolutiontomanualpageorderingproblemsandallowsuserstoaccess thedesiredpagedirectly. 2.2.Selectingasectiontype 2.2.1.Specifyingasection Thisisdoneviauseofthesectionargumenttoman man1exit willlookforexit.1*insection1ofthemanual.Ifexit.1exists,itwillbedisplayedinpreferenceto exit.1foo man1fooexit willlookforexit.1foo*insection1ofthemanual.Theasterisk(*)representsawild-cardofany typeorlength,includinglengthzero. Foranargumenttobeinterpretedasasectionnameratherthanapagename,itmusteither beginwithadigit,orbeincludedinthestandardsectionlist.Thedefaultsectionlistisdefined ininclude/manconfig.htobe1,n,l,8,3,2,5,4,9,6and7.Thisshouldbemodifiedinorder andcontenttomeetthelocalconventions. Everysubdirectorysectionnameintheentiresystemmustbeinthelist,includingsectionsfound inimportedmanualpagehierarchies.Theorderisimportantbecauseinnormaloperation,man willonlydisplaythefirstmanualpageitfindsthatmeetsthesearchcriteria.Usingthe−−all argumentwillcausemantoattempttodisplayallmanualpagesthatmeetthecriteria.See man(1)forfurtherinformation. Havinganexcessofsectionslistedwillnotslowmandown. 4 mandb−2.3.x manualv0.5 April18,1995 2.2.2.Specifyinganextension Ifthesectionisunknown,butthepackageextensionis,itispossibletousetheextensionargument man−efooexit tosearchinallsectionsformanualpagesnamedexitfrompackagefoo. mandb−2.3.x manualv0.5 April18,1995 3.Filesystemstructure 3.1.Manualpagehierarchies Itisoftencommonformanualpagesystemstohavemorethanonemanualpagehierarchy.Indeed oneofthesystemsIusehasthefollowinggloballyaccessiblehierarchies /usr/man /usr/local/man /usr/local/tex/man /usr/local/pbm/man /usr/X11R6/man /usr/openwin/man /usr/local/packages/pvm/man Afullsystem$MANPATHwouldbeacolonseparatedlistofthesedirectoriesTheorderis important,andisobservedbymandb’ssearchalgorithms.Theorderisverymuchrelatedtothe users$PATHenvironmentvariable,andshouldbesetonaperuserbasis,ornotsetatall.Ifa user’s$PATHcauses /usr/local/packages/bin/foobar tobeexecutedinpreferenceto /usr/bin/foobar, itisessentialthat manfoobar displaysthemanualpagelocatedwithin /usr/local/packages/man ratherthanwithin /usr/man Toensurecorrectorder,theprogrammanpathmaybeusedtosetthe$MANPATHenvironment variable.Seemanpath(1)andmanpath(5)fordetails. 3.2.SettingtheMANPATH IfusingaBournestyleloginshellsuchasbash,ksh,orzsh,thecommands exportMANPATH MANPATH=‘manpath−q‘ canbeaddedto$HOME/.profile IfusingaCstyleloginshellsuchascshortcsh,thecommands setenvMANPATH‘manpath−q‘ canbeaddedto$HOME/.login N.B.$PATHmustbesetpriortousingmanpath.Thesettingof$MANPATHisactually unnecessaryasthemandb−2.3.xutilitieswilldynamicallydeterminethemanpathif$MAN-PATHisunset. 3.3.OtherOS’smanualpages Itiscommontohavecollectionsofheterogeneouscomputersystemslinkedtogetherinanetwork. 6 mandb−2.3.x manualv0.5 April18,1995 Insomecircumstances5itisadvantageoustobeabletoaccessthemanualpagesoftheseother systemsdirectlyfromyoursystem.Thisfeatureisknownasalternatesystemsupport.The acceptedwaytosetupthissupportistoNFSmounttherespectivesystems’manualpagehierarchiesunderthenativemanualpagehierarchies.Anexample: SystemManualpagehierarchy <local>/usr/man newOS/usr/man/newOS userix/usr/man/userix <local>/usr/local/man newOS/usr/local/man/newOS userix/usr/local/man/userix RatherthanhavemultipleNFSmountsfromasinglemachine,thismaybeaccomplishedbyNFS mounting <other-sys>:/usr somewhereonthelocalsystemandusingsymboliclinkswithinthemanualhierarchies.Toaccess thesealternatesystemsusingmanusethe−moption,eg. man−−all−−systemuserix:newOS5passwd wouldprovidemanualpagesshowingthestructureof/etc/passwdonsystemsuserixandnewOS inthatorder.Amanualpagewouldnotbedisplayedaboutthelocalsystemsconventions.Please readtherelevantmandbutility’smanualpageforfurtherandmorespecificinformation. 3.4.NLSmanualpages NLSmanualpagesshouldbeputinNLSsubdirectoriesofastandardmanualpagehierarchy.A tableillustratingtheconceptisreproducedfromthe“LinuxFilesystemStructure”6(FSSTND) manualfromwhichfurtherinformationmaybeobtained. LanguageTerritoryCharacterSetDirectory English—ASCII/usr/man/en EnglishUnitedKingdomASCII/usr/man/enGB EnglishUnitedStatesASCII/usr/man/enUS FrenchCanadaISO8859-1/usr/man/frCA FrenchFranceISO8859-1/usr/man/frFR GermanGermanyISO646/usr/man/deDE.646 GermanGermanyISO6937/usr/man/deDE.6937 GermanGermanyISO8859-1/usr/man/deDE.88591 GermanSwitzerlandISO646/usr/man/deCH.646 JapaneseJapanJIS/usr/man/jaJP.jis JapaneseJapanSJIS/usr/man/jaJP.sjis JapaneseJapanUJIS(orEUC−J)/usr/man/jaJP.ujis Eachofthesedirectoriesaretheninterpretedasmanualpagehierarchiesthemselvesandmaycontaintheusualsectionsubdirectories.AccesstoNLSmanualpagesisachievedviauseofthesetlocale(3)functionwhichqueriesuserenvironmentvariablestodeterminethecurrentlocale. 5writingportablesoftwareinstantlycomestomind 6writtenandmaintainedbyDanielQuinlan<quinlan@yggdrasil.com> 7 mandb−2.3.x manualv0.5 April18,1995 Internallytothemandbutilities,thislocalestringisappendedtoeachmanpathelementandthe resultantNLSmanpathelementissearchedbeforethestandardmanpathelement.Inthisway,an NLSmanualpagethatmatchesthesearchcriteriawillbeshownbeforeorinplaceofthestandard AmericanEnglishpage. Ifauser’s$MANPATHconsistsoforisdeterminedas /usr/local/man:/usr/man:/usr/X11R6/man andtheirlocaleissettodeDE,thecommand man−−systemuserix:manfoobar wouldproducethefollowinginternalmandbmanpathelements /usr/local/man/userix/deDE /usr/local/man/userix /usr/man/userix/deDE /usr/man/userix /usr/X11R6/man/userix/deDE /usr/X11R6/man/userix /usr/local/man/deDE /usr/local/man /usr/man/deDE /usr/man/man /usr/X11R6/man/deDE /usr/X11R6/man foobarwouldbesearchedforintheorderofmanualpagehierarchieslisted. 3.4.1.ISO8859-1(latin1)manualpages BydefaultNROFFwillformatmanualpagesintoaformsuitableforatypewriterstyledevice, e.g.aterminalscreen.GNUNROFFiscapable7offormattingROFFintoaformsuitablefor8-bit latin1capableoutputdevices.Toenableoutputforsuchadevice,givetheoption −−with−device=DEVICE toconfigurewhereDEVICEisthesuitableandsupportedoutputformat,inthiscaselatin1. 3.4.2.Displayinglatin1charactersonaLinuxvirtualterminal Toenableconsolebasedviewingoflatin1charactersonaLinuxsystem,youmusthavethekbd8 packageinstalled.Thefollowingcommandsincludedwithinaninitialisationfilesuchas /etc/rc.d/rc.localwillenablethedisplayoflatin1fontsonthefirst5virtualterminals. ---<partof/etc/rc.d/rc.local>--- #sortoutthevtfont if[−x/bin/setfont];then /bin/setfont/etc/kbd/consolefonts/lat1−16.psf fi #loadthekeymaptransformationtodowhenactivatingnewfont if[−x/bin/mapscrn];then 7seenroff(5)fortheoutputdeviceformatsavailablewithyourNROFF 8writtenandmaintainedbyAndriesBrouwer<aeb@cwi.nl>.Version0.90andabovedoesnotrequiretheuseof mapscrnasillustratedinthescript. 8 mandb−2.3.x manualv0.5 April18,1995 /bin/mapscrn/etc/kbd/consoletrans/trivial fi #enablenewfont fortin12345;do echo−n−e"\033(K">/dev/tty$t done ---<partof/etc/rc.d/rc.local>--- Fordisplayunderthe“XWindowSystem”,asuitable8bitcleanterminalemulatorisrequired. 3.4.3.ViewingASCIIpagesformattedforlatin1outputdevice WhenformattinganASCIImanualpageforalatin1outputdevice,GNUNROFFwilltake advantageoftheextracharactersavailableandwillalwaysproduceatextpagecontainingsome latin1(8-bit)symbols.Thetable9below,takenfromman(1)illustratesthedifferences. DescriptionOctalISO8859-1ASCII continuationhyphen255-− bullet(middledot)267•o acuteaccent264´ ’ multiplicationsign327×x Todisplaysuchsymbolsona7bitterminalorterminalemulator,theymustbetranslatedback intostandardASCII.The−7optionwithmanwillenablethissimplereversetranslation. Thisoptionmaybeusefulifyoursitehasboth7and8-bitcapableoutputdevicesandnroffis usingthelatin1outputdevicetoformatmanualpages. 3.5.Catpages Ithasbecomestandardpracticetostoretheformattedmanualpagesondisksothatsubsequent requestsforthemanualpagedonothavetoinvolvetheformattingprocess.Thesepre-formatted manualpagesareknownascatpages.Althoughcatpagesrequireadditionaldiskstoragerequirements,theyprovideasubstantialspeedincreaseandtheiruseisrecommended. Theautomaticsupportofstoringandusingcatpagesisbroughtaboutbysimplycreatingsuitable directoriesforthem. 3.6.Catpagehierarchies Traditionally,catpageswerestoredunderthesamemanualhierarchyastheirsourcemanual pages,incat<sec>subdirectoriesratherthanman<sec>.Thissituationisratherlimitinginseveralsituations •Whenitisadvantageoustomount/usrasaread-onlyfilesystem.Catpagescannotbesup-portedinthissituationwithoutuseofsymboliclinkstovariousotherareasofthefilesystem. Thissituationisagreaterproblemifthemediaitselfisread-only,suchasCD-ROM. •WhenNFSmountingalternateOS’smanualpagehierarchies.Thealternatesystemmaybe undersomeoneelse’scontrolandtheymaynotwantcatpagesstoredontheirsystem.Infact itisusuallyagoodideatoexportthemanualpagefilesystemsread-only,orimportthemthat 9TheISO8859-1andASCIIcolumnsofthistablewillbeidenticalifthismanualwasformattedforanASCIIbased typewriterdisplay,i.e.usingNROFFinit’snativemode. 9 mandb−2.3.x manualv0.5 April18,1995 way.Itispossibletoavoidtheproblems,thistimewithevenmoresymboliclinksthatmay needperiodicupdating. •Ifthereisamixtureofnormalcatfilesandstraycats10,itisverydifficulttoperiodicallytrim thecatspacediskusagebyremovingseldomaccessedcatfiles. Toavoidalloftheseproblemssimultaneously,itwasdecidedtosupportlocalcatpagedirectory caches. 3.7.Localcatpagedirectorycaches Anylocationforcatpagehierarchymaybespecifiedinthemandbconfigurationfile.Thelocationofthedatabasecacheassociatedwitheachmanualpagehierarchywillalwaysbeattheroot ofthecatpagehierarchy.Bydefault,thecatpagehierarchyshadowsthemanualpagehierarchy. TheFSSTNDproposes/var/catmanasthelocationforsuchdirectoriesalthoughmandb−2.3.x allowsanydirectoryhierarchytobeused.TheFSSTNDpathtransformationruleisasfollows /usr/<hierarchy>/man/<locale>/man<sec>/page.<sec><ext> shouldbeformattedintothecatfile /var/catman/<hierarchy>/<locale>/cat<sec>/page.<sec><ext> wherethe<locale>directorycomponentmaybemissingand<ext>maybeanemptystring. Thesuggestionisthatstraycatsarelocatedinthetraditionalhierarchyunder/usrwhereasrecreatablecatpagesarestoredunderthelocalwritablehierarchy/var/catman.manfollowsstrict rulesindeterminingwhichfileisdisplayed. Asanexample,thefollowingrouteistakenifallthreefilesexist. (1)Checkrelativetimestampsofthemanualfileandthetraditionalcatfile.Ifthecatfileis uptodate(hasamorerecenttimestamp),displayit. (2)Thetraditionalcatfileisoutofdate.Checkrelativetimestampsofthemanualfileand thealternatecatfile.Ifthecatfileisuptodate,displayit. (3)Thealternatecatfileisoutofdate.Formatthemanualfileanddisplaytheresultinthe foreground,whileupdatingthealternatecatfileinthebackground. 10catfilesthathavenosourcemanualpage,i.e.theycannotberecreated. 10 mandb−2.3.x manualv0.5 April18,1995 4.Compression 4.1.Compressedmanualpages Itispossibletomaintainasystemofcompressedmanualpages.Theuseofthisfeatureisnotrecommendedforsystemsthathaveadequatediskspacetostoretheirmanualpagesuncompressed. Subsequentdecompressionofthesemanualpageswillcauseseveralbottlenecksintheformatting process. Presently,thecompressionextension/decompressorpairsmustbeknownatcompiletimealthough anynumbermaybedefinedandused.Thefollowingstructureispredefinedinmandb−2.3.x ExtensionDecompressor gzgzip−dc zgzip−dc Zcompress−dc Itisarelativelyeasyoperationtoincludefurtherpairsinthisstructure.Seeinclude/compsrc.h fordetailsandanexample. Supportforcompressedmanualpagesiscompiledintothemandb−2.3.xutilitiesbydefault.To completelydisablethissupport,editinclude/config.handcommentoutthefollowingline #defineCOMPSRC1 Thiswillenableaminorspeedincrease,butnotethatsupportforstraycatswithanycompression extensionotherthanthedefaultwillalsobedisabled. 4.2.Compressedcatpages mandb−2.3.xcompressescatfilesbydefault.Duringconfiguration,configurewilltrytofind gzipandifso,allcatfilesproducedbymanwillbecompressedwith gzip−7c andhavea.gzextensionappended.Ifgzipisnotfound, compress−c isusedasthecompressorandtheextension.Zisappended. Tostorecatfilesinanuncompressedstateandtodisablecompressedextensionprocessingcompletely,editinclude/config.handcommentoutthefollowingline #defineCOMPCAT1 4.2.1.Straycats Normally,manwillonlylookforcatfileswiththedefaultcompressionextension.Thedefault compressionextensionisdependentonthedefaultcompressorandmaybeanemptystringifthe supportforcompressedcatsisdisabled. Itispossibleforasystemtobesuppliedwithstraycatfileslocatedinthetraditionalcatpage hierarchy.Tomakemattersworse,theymayhavecompressionextensionsotherthanthedefault andresideonread-onlymedia.Insuchcircumstances,straycatfileswillbeacceptedwithany compressionextensionthatisalsosupportedformanualpages. Thisspecialtreatmentofstraycatpagesisremovedifsupportforcompressedmanualpagesis turnedoffornotavailable. 11 mandb−2.3.x manualv0.5 April18,1995 5.Formatting Asalreadypointedoutintheintroduction,therearetwoprimaryformatterscommontoUNIX: NROFFandTROFF. Inthefollowingsections,IwillusethetermTROFFtodescribethetypesetterformatterand NROFFtodescribethetypewriterformatter.ThetermROFFwillbeusedtodescribeageneric formatter. 5.1.GROFF IfusingtheGROFFpackage,thereisafurtherchoice,GROFFitself.Essentially,GROFFforms apipelineofprocessorsincludingTROFFandanoutputprocessorwhichtranslatestheditroff producedbyTROFFintotheappropriateoutputformat.Thedefaultoutputformat,ordevice, forGROFFisPostScript.Anythingelsemustbespecifiedusingthedeviceargument.ToillustrateGROFF,thecommand groff−Tdvi/dev/null willformthefollowingpipeline troff−Tdvi/dev/null|grodvi IfGROFFistiedtoman’s−Toption,itisstillpossibleformantoproduceditroffviauseof the−Zoption. InGROFF1.09,NROFFisbundledasashellscriptthatcallsGROFF,whichinturncalls TROFFwiththedefaultoptions−Wall−mtty-char−Tascii,passingtheresultthrough grottybeforeitfinallyreachesthescreen. Itisimperativethatthescriptdoesnotpasspre-processingoptionstoGROFFcommandlineas mantakescareofthisseparately.Thefiletools/nroffscriptmaybeusedasabasisforan NROFFscriptifyoursystemiswithoutone. 5.2.Devices BothNROFFandGROFFmayallowoutputdeviceselection.Asmentionedpreviously,classic NROFFproducesoutputsuitableforatypewriterdevice,classicTROFFproducesoutputsuitableforaC/A/TandGROFFproducesoutputsuitableforaPostScriptinterpretingdevice. 5.3.Macros ThereareseveralROFFmacrosinexistencethataresuitableformanualpages.Unfortunately, theytendtobeincompatiblewitheachother. Duringconfiguration,configurewillattempttodetermineasuitablemacroforthelocalsystem’s manualpagecollection.ItattemptstouseNROFFwiththefollowingthreemacropackages: macropackagemacrofilenamenroffcommand andoctmac.andocnroff−mandoc antmac.annroff−man doctmac.docnroff−mdoc Thefirstthatsucceedsisused.Macroandocissuitableformanualpageswrittenusingeitheran ordocmacrocommands,butnotboth. 5.4.Pre-formatprocessors(pre-processors) Manualpagesmayrequirepre-processingbyanyofthefollowing 12 mandb−2.3.x manualv0.5 April18,1995 ProgramIDPre-processes eqneequations tblttables grapggraphs picppictures referrAbibliography vgrindvprogramlistings Itispossibletoassignadefaultpre-processorlistthatallmanualpageswillbepassedthrough priortotheprimaryformatter.Bydefault,thisisempty.Todefineadefaultlist,edit include/manconfig.handun-commentthefollowingline /*#defineDEFAULTMANROFFSEQ"t"*/ whichwillenabletblprocessingbydefault.Tochangethelist,replacethetwithasuitablestring ofprocessorID’s. Pre-processoptionsmaybeprovidedatruntimeinvariousforms,butingeneralthepre-processorsrequiredbyeachmanualpageisindicatedinthefirstlineofthemanualpageitself.See man(1)fordetails. 5.5.Formatscripts Itisverylikelythatalternatesystemsmanualpagesmayrequirenon-standardmacropackagesor possiblyevenspecialpre-processors.Totacklesuchproblems,specialformatscriptsmaybecre-atedonapermanualhierarchybasis. Ifthefile <manualhierarchy>/mandbnfmt existsandisexecutable,itisexpectedtobeabletocorrectlyformatamanualpageoriginating from<manualhierarchy>toitsstandardoutput.Itwillbesuppliedwitheithertwoorthree arguments: •manualpagefilename •pre-processorstring •ouputdevice(optional) Similarly,iftheoption−T<device>or−twassuppliedtomanandthefile <manualhierarchy>/mandbtfmt existsandisexecutable,itwillbeusedinthesameway. Anexampleofsuchascript,suppliedbyMarkusArmbruster<armbru@pond.sub.org>,whoprovidedsupportforexternalformatterscripts,canbefoundastools/mandb[nt]fmt ThescriptcanbeusedasbothaNROFFandTROFF/GROFFformatscriptandcanbe installedasmandbnfmtandhardlinkedtomandbtfmtaftermodificationappropriateforyour particularsite. 13 mandb−2.3.x manualv0.5 April18,1995 6.Theindexdatabasecaches Asmentionedintheintroduction,mandb−2.3.xusesdatabaselookupstosearchformanualpage locationsandinformation.Whenperformingamanualpagelookuporabasicwhatissearch,the databasesaresearchedin key→content modeandareasfastastheunderlyingdatabasescanbe.Whenperformingaproposorspecial whatissearches,thedatabasesaresearchedinalinearway,whichalthoughfarmoreexpensive thankeyedlookup,isnoworsethantraditionaltextbasedfilesearching. 6.1.indexdatabaselocation Thedatabasesarealwayslocatedattherootofthecatpagehierarchy,whetherthisisthesame asthemanualpagehierarchyornot.Asfilelockingmechanismsareemployedtoensurethatconcurrentprocessesdonotupdateadatabasesimultaneously,itisalmostimperativethatthe databasesresideonalocalfilesystemsincefilelockingacrossNFSfilesystemsmaybeunavailable orflaky.Toavoidsuchproblems,mancanbecompiledwithoutdatabasemaintenancesupport. Seethesectiontitled"Modesofoperation"fordetails. 6.1.1.Manualhierarchieswithnoindexdatabase Itispossibleforthemandb−2.3.xutilitiestooperatewithoutaidfromanindexdatabase.Under suchcircumstances,searchmethodswillresorttofileglobbingandwhatistypesearchesareperformedonanytraditionalwhatistextdatabasesthatmayexist.Onlythetraditionalcathierarchyissearchedforcatfiles. 6.1.2.Usermanualpagehierarchies Ausermayhaveanynumberofpersonalmanualpagehierarchieslistedintheir$MANPATH. Bydefault,manwillmaintainmandbcreateddatabasesattherootofusermanualpagehierarchies.Thedefinitionofausermanualhierarchyisthatitdoesnothaveanentryinthemandb configurationfile.Seemanpath(5)fordetails. 6.2.Contentsofanindexdatabase Therearefourkindsofentryinanindexdatabase. (1)Adirectentryregardingaparticularmanualpage.Manualpagesthatareuniqueinterms ofnameusejustasingleentryinthedatabaseandcanbelookedupbysimplyusingthe nameasthekey. (2)Acommonnameindexentrythatliststheextensionsofallofthemanualpagessharing thecommonindexentryname.Manualpagesthatsharecommonnames,buthavedifferingextensionseachhaveasingledatabaseentry,butthistimetheyarelookedupwitha keycomprisedoftheirnameandtheirextension.Theentiresetofcommonnamedpages alsohasancommonnameindexentrythatinformsoftheextensionsavailable. (3)Anindirectentrythathasapointertotherealentry.Manualpagesthatarewhatisreferencestoaparticularpagedonotphysicallyexistsotheyhaveapointertotheentrycontainingthelocationoftherealmanualpage. (4)Specialidentificationentries.Therearetwospecialkeynames,“$mtime$”thatreferences anintegerdescribingthelastmodificationtimeofthedatabaseand“$version$”thatidentifiesthedatabasestorageschemeversion. Inthefollowingentries,thecharacter“|”willbeusedtoseparatethefields.Inrealityatabis used.Directandindirectentriestakestheform: 14 mandb−2.3.x manualv0.5 April18,1995 <name>→<ext>|<sec>|<mtime>|<ID>|<ref>|<comp>|<whatis> Commonnameindexentriestaketheform: <name>→|<ext1>|<ext2>|<ext3>|...<extn> andcommonnamedirectorindirectentriestaketheform: <name>|<ext>→<ext>|<sec>|<mtime>|<ID>|<ref>|<comp>|<whatis> whereineachcasethefilenamebeingrepresentedisformedas <manualhierarchy>/man<sec>/<name>.<ext>.<comp> inthecaseofamanualpage,or <cathierarchy>/cat<sec>/<name>.<ext>.<comp> inthecaseofastraycat. Ifanyofthefieldswouldbeempty,asingle“−”isstoredinitsplace.<comp>representsthe compressionextension.<mtime>isanintegerrepresentingthelastmodificationtimeofthe manualpage,<ref>pointstotheentrycontainingthelocationoftherealpageand<ID>isone ofthefollowingidentificationletters. ID#defineDescription AULTMANultimatemanualpage,thefullsourcenrofffile BSOMANmanualpagecontaininga.sorequesttoanULTMAN CWHATISMANvirtualwhatisreferencedpagepointingtoanULTMAN DSTRAYCATcatpagewithnosourcemanualpage EWHATISCATvirtualwhatisreferencedpagepointingtoaSTRAYCAT TheIDillustratestheprecedence.Sometypesofmanualpagecanbereferencedbyseveralmeans, e.g..sorequestedandwhatisreferred.Insuchacase,onlyonereferencemustbestoredinthe database,theprecedenceleveldecideswhich. 6.2.1.Favouringstraycats Withtheaboverulesofprecedence,itispossibleforavalidstraycatpagetobereplacedbya whatisreferredpagesharingidenticalname-space. Ifyouwouldliketoseethestraycatpagekill(1)insteadofthebashbuiltins(1)pagereferenced bykill(1)editlibdb/dbstorage.handun-commentthefollowingline /*#defineFAVOURSTRAYCATS*/ 6.2.2.Accessdb Asimpleprogram,accessdbisincludedwithmandb−2.3.x.Itwilloutputthedatacontained withinamandbdatabaseinahumanreadableform.Bydefault,itwilldumpthedatafrom /var/catman/index.<db-type>,where<db-type>isdependentonthedatabaselibraryinuse. Supplyinganargumenttoaccessdbwilloverridethisdefault.Tabsarereplacedintheoutputby atilde“˜ ”inthekeyfieldandasinglespaceinthecontentfield accessdbisnotcompiledbydefault.Type makeaccessdb inthesrcdirectorytocompileit. 15 mandb−2.3.x manualv0.5 April18,1995 6.2.3.Exampledatabase Asanexampleofbothaccessdbandthedatabasestoragemethod,theoutputof src/accessdbman/index.bt afterfirstrunning src/mandbman fromthetoplevelbuilddirectoryisincludedbelow. $mtime$->"795987034" $version$->"2.3.1" apropos->"11795981542A--searchthemanualpagenamesanddescriptions" catman->"88795981544A--createorupdatethepre-formattedmanualpages" man->"11795981542A--aninterfacetotheon-linereferencemanuals" mandb->"88795981544A--createorupdatethemanualpageindexcaches" manpath->"15" manpath˜ 1->"11795981542A--determinesearchpathformanualpages" manpath˜ 5->"55795981543A--formatofthe/etc/mandb.configfile" whatis->"11795981543A--searchthemanualpagenames" zsoelim->"11795981543A--satisfy.sorequestsinroffinput" 6.3.Databasetypes mandb−2.3.xhassupportforvariouslowleveldatabaselibrariescommonlyinusetoday.The interfacestothelibrariesareknownas •ndbm(UNIX) •gdbm(GNU) •btree(BerkeleyDB) mandb−2.3.xcurrentlydoesnotholdmorethanonedatabaseopenatanytime,so •dbm(UNIX) supportcouldbeaddedinthefuture. 6.4.limitations Thegeneraldifferencesandlimitationsarebestcomparedinatable. Contentmemory File Concurrent nametypelimitaccess NameType Shareable ndbmhashindex11static1Kbnoneno gdbmhashindex.dbdynamic−filelockingno btreebinarytreeindex.btstatic−noneyes Thosetypesthathavenobuiltinconcurrentaccessstrategy,areprovidedwithflock(2)basedfile lockingbymandb−2.3.x. Asbtreeisnoticeablyfasterwhendoingmansearches,mainlyduetothefastinitializationof thedatabases,itisthepreferredlibraryinterface.configurewilllookforbtree,gdbmandthen finallyndbmroutineswhenconfiguringmandb−2.3.x. 11ndbmdatabasesarephysicallyrepresentedbytwofiles:index.dirandindex.pagbutarereferredtosimplyasindex bytheinterfaceroutines. 16 mandb−2.3.x manualv0.5 April18,1995 6.5.Sharingdatabasesinaheterogeneousenvironment Itmaybenecessaryoradvantageoustosharedatabasesacrossplatforms,regardlessofthepotentialfilelockingproblems. AnexamplewouldbeauserhavingapersonalmanualpagehierarchyinanNFSbasedhome directoryenvironment,wherebythehomedirectoryisheldonandmountedfromasinglemachine inaheterogeneousnetwork. Inthiscontext,thedatabasecachewillhavethesamenameandresideinthesameplaceonall machines.Thereareatleasttwowaystodealwiththisproblem. •Hacktheinclude/manconfig.hfileoneachplatformtoprovideauniquedatabasenamefor eachsystem.Nodatabaseswillbeshared. •InstallandusetheBerkeleyDBdatabaseinterfacelibraryoneachplatform.Thesedatabases canbesharedacrossbig-endian/little-endianplatformsalthoughadatabasecreatedonabig-endianplatformwillsufferasmallaccesspenaltywhenusedbyalitle-endianmachineand vice-versa. mandb−2.3.x manualv0.5 April18,1995 7.Miscellaneous 7.1.Modesofoperation Themandbutilitiescanoperateinmanydifferentmodes,allowingvaryingdegreesoffreedom, functionalityandsecurity.Nomoderequiresthatthemanualpagehierarchiesbewritable. (1)Defaultmode manissetuidtotheuserMANOWNERwhichis‘man’bydefaultandischangeablevia optionstoconfigure.mandb,ifrunbythesuperuserorMANOWNER,createsglobally accessibleindexdatabasesownedbyMANOWNER.Oncethedatabasesarecreated,man willupdateentriesinthemifitfindsnewlyinstalledmanualpagesordeleteentriesifmanualpagesareremoved.Inthismodeitispossibleforamaliciousmanusertodeliberately lockadatabaseasawriter,thusdenyingreadaccesstootherusers. Ifcatdirectoriesexistandhavethecorrectpermissions,manwilltakecareofproducingcat files.ThesewillbeownedbyMANOWNER.Thedefaultpermissionsofbothcatfilesand databasesis0644. (2)Nomandatabaseupdates Thismodealsorequiresmantobesetuid,butisfavouredwheredatabasesmustbeshared inanenvironmentunfriendlytokernellockingprocedures,eg.NFS.Italsopreventspossible ‘denialofservice’attacksbymaliciousmanusersasmanneveropensthedatabasesasa writerinthismode.Toreplacethefunctionalitylostbydisallowingmanwriteaccessto thedatabases,mandbmustbererunwhenevernewmanualpagesareinstalled.Failureto dosowillresultinmanbeingunabletofindanddisplaythenewlyaddedmanualpages. Asmandblackstheabilitytodeletedatabaseentriesformanualpagesthathavebeen removed,itisnecessarytousethe−−createflagwhenevermanualpagesareremovedfrom thefilesystem.Eachindexdatabasemaybeownedbyanarbitraryuserwhowillhavesubsequentwriteaccesstothedatabase.Catfilesarecreatedinthesamewayasformode(1) above. Tousethemandbutilitiesinthismode,editinclude/manconfig.handcommentout ‘#defineMANDBUPDATES’ (3)Nomandatabaseupdatesorcatproduction manisinstallednotsetuid.Thismodeofoperationprobablyoffersthehighestlevelof securitybutitrequireshigherlevelsofmaintenancethanothermodesduetotherestrictions imposeduponman.Eachdatabaseisownedbyanarbitraryuserasinmode(2).Eachcat hierarchyisalsoownedbyanarbitraryuserwhoisresponsibleforcreatingcatfilesusing catmanwhenevernewmanualfilesareinstalled.manwillbecompletelypassiveinit’s action,ie.noindexdatabaseswillbewrittentoandnocatfilesareeverproduced. Tousethemandbutilitiesinthismode,supplytheoption‘−−disable−setuid’toconfigureandeditinclude/manconfig.h,commentingout‘#defineMANDBUPDATES’and ‘#defineMANCATS’afterrunningconfigure. (4)Wideopen manisinstallednotsetuid.Thismodeissimilarinoperationtothemajorityofvendor supplied,nonsetuid,catfilesupportingmanualpagersuites.Itisnotrecommended.The databasesareownedbyanarbitraryuserwhomaintainsthemusingmandb.mandoes notupdatethedatabases.Catfilesareproducedandstoredinworldwritablecatdirectoriesandhaveworldwriteaccessthemselves. Tousethemandbutilitiesinthismode,supplytheoption‘−−disable−setuid’toconfigure,editinclude/manconfig.handcommentout‘#defineMANDBUPDATES’andchange thedefinitionofCATMODEfrom0644to0666. Othervariationscanalsobeused.Infactitispossibleformantoactuallycreateindex databases,usuallythejobofmandb,forusersprivatemanualpagehierarchies.Thisisenabled byeditinginclude/manconfig.handun-commentingthe‘/*#defineMANDBCREATES*/’ 18 mandb−2.3.x manualv0.5 April18,1995 line.mandb−2.2operatedinthismanner. Insummary,include/manconfig.hcontainsdefinitionsfor •MANDBCREATES •MANDBUPDATES •MANCATS •CATMODE •DBMODE andthesetuidinstallationandoperationofmanismodifiedbysupplyingeitherofthefollowing optionstoconfigure: •−−enable−setuid=USER •−−disable−setuid 7.2.NLSmessagecatalogues mandb−2.3.xhasbuiltinsupportfornativelanguagemessagecatalogues.Thatis,itcanissue messagesinthelocaleoftheuserschoice.Thiswillonlyoccurifthelocale’stranslationhasbeen written.Beforeundertakingatranslation,pleasecontacttheauthorwhowillbemaintainingalist ofsuchactivity. Currently,thefollowingtranslationsexist •*none* 7.3.Credits Iwouldliketothankthefollowingpeoplefortheirtime,effort,support,ideasandcodewhich wentintomandb−2.3.x MarkusArmbruster<armbru@pond.sub.org> CalebEpstein<epsteincaleb@jpmorgan.com> ZoltanHidvegi<hzoli@cs.elte.hu> NilsMagnus<magnus@unix-ag.uni-kl.de> DanielQuinlan<quinlan@yggdrasil.com> 19 Glossary manualpage Afilecontainingdescriptionsrelatedtotheuseofafunctionorprogramorthestructureof afile.Thenameofthefileisformedfromthetitleofthemanualpagefollowedbyaperiod followedbythenameofthesectionthatitresidesin,optionallyfollowedbyanextension. TheformatofthefileisNROFFandmaybecompressed,havingasuitablecompression extensionappended. catpage Aformattedmanualpagesuitableforviewinginaterminal. straycatpage Acatpagethatdoesnothavearelativemanualpageonthesystem,ie.onlythecatpage wassuppliedorthemanualpagewasremovedafterthecatpagehadbeencreated. section Eachmanualpageorcatpagehierarchyisdividedintosections,eachsectionhavingit’sown directory.manualpagehierarchysectionnamesbeginwith‘man’andcatpagesectionswith ‘cat’. extension Apackagemayprovidemanualpageswithfilenamesendinginapackage-specificextension name.Thisallowsmanualpageswiththesametitletocoexistinthesamemanualpage hierarchyandsectionwithoutsharingthesamefilename.Italsoprovidesafurthermechanismformantoselectthecorrectmanualpage. manualpagehierarchy Adirectorytreedividedintomanualpagesections,eachcontainingacollectionofmanual pages. catpagehierarchy Adirectorytreedividedintocatpagesections,eachcontainingacollectionofcatpages. traditionalcatpagehierarchy Thesamelocationasthemanualpagehierarchy. alternatecatpagehierarchy Aseparatelocationtothatofthetraditionalcatpagehierarchy. traditionalcatpage Acatpagelocatedinatraditionalcatpagehierarchy. alternatecatpage Acatpagelocatedinanalternatecatpagehierarchy. i Contents 1.Introduction....................................................................................................................1 1.1mandb−2.3.x..........................................................................................................1 1.1.1Theconcept....................................................................................................1 1.2Themanualpagesystem..........................................................................................2 1.3Sectionsofthemanual.............................................................................................2 1.4Theformatofmanualpages.....................................................................................3 1.5Argumentstoconfigure............................................................................................3 2.ThespecificsofSections..................................................................................................4 2.1Packagespecificmanualpagesections.....................................................................4 2.2Selectingasectiontype............................................................................................4 2.2.1Specifyingasection........................................................................................4 2.2.2Specifyinganextension..................................................................................5 3.Filesystemstructure........................................................................................................6 3.1Manualpagehierarchies...........................................................................................6 3.2SettingtheMANPATH............................................................................................6 3.3OtherOS’smanualpages.........................................................................................6 3.4NLSmanualpages....................................................................................................7 3.4.1ISO8859-1(latin1)manualpages..................................................................8 3.4.2Displayinglatin1charactersonaLinuxvirtualterminal...............................8 3.4.3ViewingASCIIpagesformattedforlatin1outputdevice...............................9 3.5Catpages..................................................................................................................9 3.6Catpagehierarchies.................................................................................................9 3.7Localcatpagedirectorycaches................................................................................10 4.Compression....................................................................................................................11 4.1Compressedmanualpages........................................................................................11 4.2Compressedcatpages...............................................................................................11 4.2.1Straycats........................................................................................................11 5.Formatting.......................................................................................................................12 5.1GROFF....................................................................................................................12 5.2Devices.....................................................................................................................12 5.3Macros......................................................................................................................12 5.4Pre-formatprocessors(pre-processors).....................................................................12 5.5Formatscripts..........................................................................................................13 6.Theindexdatabasecaches..............................................................................................14 6.1indexdatabaselocation............................................................................................14 6.1.1Manualhierarchieswithnoindexdatabase....................................................14 6.1.2Usermanualpagehierarchies.........................................................................14 i 6.2Contentsofanindexdatabase.................................................................................14 6.2.1Favouringstraycats.......................................................................................15 6.2.2Accessdb.........................................................................................................15 6.2.3Exampledatabase...........................................................................................16 6.3Databasetypes.........................................................................................................16 6.4limitations................................................................................................................16 6.5Sharingdatabasesinaheterogeneousenvironment..................................................17 7.Miscellaneous...................................................................................................................18 7.1Modesofoperation...................................................................................................18 7.2NLSmessagecatalogues...........................................................................................19 7.3Credits......................................................................................................................19